Crate notify

Cross-platform file system notification library

Source is on GitHub: https://github.com/notify-rs/notify

Installation

[dependencies]
notify = "4.0.18"

Examples

Notify provides two APIs. The default API debounces events (if the backend reports two similar events in close succession, Notify will only report one). The raw API emits file changes as soon as they happen. For more details, see Watcher::new_raw and Watcher::new.

Default (debounced) API

extern crate notify;

use notify::{Watcher, RecursiveMode, watcher};
use std::sync::mpsc::channel;
use std::time::Duration;

fn main() {
    // Create a channel to receive the events.
    let (tx, rx) = channel();

    // Create a watcher object, delivering debounced events.
    // The notification back-end is selected based on the platform.
    let mut watcher = watcher(tx, Duration::from_secs(10)).unwrap();

    // Add a path to be watched. All files and directories at that path and
    // below will be monitored for changes.
    watcher.watch("/home/test/notify", RecursiveMode::Recursive).unwrap();

    loop {
        match rx.recv() {
           Ok(event) => println!("{:?}", event),
           Err(e) => println!("watch error: {:?}", e),
        }
    }
}

Using the default API is easy, all possible events are described in the DebouncedEvent documentation. But in order to understand the subtleties of the event delivery, you should read the op documentation as well.

Raw API

extern crate notify;

use notify::{Watcher, RecursiveMode, RawEvent, raw_watcher};
use std::sync::mpsc::channel;

fn main() {
    // Create a channel to receive the events.
    let (tx, rx) = channel();

    // Create a watcher object, delivering raw events.
    // The notification back-end is selected based on the platform.
    let mut watcher = raw_watcher(tx).unwrap();

    // Add a path to be watched. All files and directories at that path and
    // below will be monitored for changes.
    watcher.watch("/home/test/notify", RecursiveMode::Recursive).unwrap();

    loop {
        match rx.recv() {
           Ok(RawEvent{path: Some(path), op: Ok(op), cookie}) => {
               println!("{:?} {:?} ({:?})", op, path, cookie)
           },
           Ok(event) => println!("broken event: {:?}", event),
           Err(e) => println!("watch error: {:?}", e),
        }
    }
}

The event structure is described in the RawEvent documentation, all possible operations delivered in an event are described in the op documentation.

Re-exports

• pub use self::op::Op;
• pub use self::inotify::INotifyWatcher;
• pub use self::null::NullWatcher;
• pub use self::poll::PollWatcher;

Modules

• inotify
  Watcher implementation for the inotify Linux API
• null
  Stub Watcher implementation
• op
  Contains the Op type which describes the actions for an event.
• poll
  Generic Watcher implementation based on polling

Structs

• RawEvent
  Event delivered when action occurs on a watched path in raw mode

Enums

• DebouncedEvent
  Event delivered when action occurs on a watched path in debounced mode
• Error
  Errors generated from the notify crate
• RecursiveMode
  Indicates whether only the provided directory or its sub-directories as well should be watched

Traits

• Watcher
  Type that can deliver file activity notifications

Functions

• raw_watcher
  Convenience method for creating the RecommendedWatcher for the current platform in raw mode.
• watcher
  Convenience method for creating the RecommendedWatcher for the current platform in default (debounced) mode.

Type Aliases

• RecommendedWatcher
  The recommended Watcher implementation for the current platform
• Result
  Type alias to use this library’s Error type in a Result